Technotools

home *** CD-ROM | disk | FTP | other *** search

/ Technotools / Technotools (Chestnut CD-ROM)(1993).ISO / lang_c / c_windw / summary.doc < prev next >

Wrap

Text File | 1987-12-30 | 48KB | 1,182 lines

Marietta Systems "c_wndw" Toolkit ================================= A toolkit for Turbo C and Quick C that provides windows, menus, formatted entry, and file access functions. This toolkit makes it easy to write C programs of professional appearance, quality, and performance. 1 - DESCRIPTION 2 - INSTALLATION 3 - QUICK REFERENCE 4 - REVIEW OF SAMPLE PROGRAMS 5 - HEADER FILES 6 - CUSTOMIZATION 7 - ERROR REPORTING 8 - FUTURE ENHANCEMENTS This manual and the c_wndw computer software is the copyright of Marietta Systems, Inc., 1987. Marietta Systems, Inc. is located in Cobb County, Georgia. Duplication of the shareware-issued computer software and this manual for non-commercial purposes is encouraged. Amendment or sale of the computer software or manual not permitted except as specifically authorized in writing by an officer of Marietta Systems, Inc. Marietta Systems does NOT warrant that the computer software will meet your requirements or that the operation of the computer software will be uninterrupted and error free. You are solely responsible for the selection and use of the computer software to achieve your intended results and for the results actually obtained. Product specifications and features are subject to change without notice. dBase III Plus is a trademark of Ashton-Tate. Marietta Systems "c_wndw" Toolkit is a Trademark of Marietta Systems, Inc. 1. DESCRIPTION =========== This C language toolkit provides input and output windowing facilities operating at professional speeds. The output windowing facilities use memory mapping for instantaneous screen display, take full advantage of color monitors, and provide automatic editing of entry and output fields. Pull down and pop-up menu functions, help screens and multi-layered windows easily provide a sophisticated user interface. The toolkit is designed for both novice and intermediate C programmers who want full screen, color, cursor control and windowing facilities without programming complex escape sequences or DOS-level interrupts, and for experienced programmers who require a set of fast I/O windowing functions. A full set of file access functions are provided that trap and handle all usual errors. Access is supported to ASCII, dBase III Plus, hashed random, and relative files. The function key map facility allows the programmer to easily enable and disable function keys, and have the disabled keys immediately rejected by the c_wndw software when pressed by an operator. Versions of the toolkit are available for the three main compilers for IBM PC systems, Borland Turbo C, Lattice C, and Microsoft Quick C. The shareware issue software is available for Turbo C and Quick C. The toolkit provides the following facilities: o Very fast output to the screen o Field editing on entry of numeric and date fields o 'UNDO' and 'HELP' facilities o Cursor control within the bounds of the current window o Automatic change of colors between windows o Pull down and pop-up menu functions o Flexible control of the use of the function keys o Error and message zones at the bottom of the screen o Optional status line at the top of the screen o US and foreign formats for date and decimal presentation o File access functions provide full error trapping o Field justification o dBase III Plus '.DBF' files The subscription fee of $35 is strongly recommended for all users of this software to take advantage of the facilities offered by the subscription and to receive the official manual. In addition, Marietta Systems offers Corporate, Development, and Educational license agreements with full source code availability. Ask for details when you send in your subscription fee. 1.1 The subscription fee -------------------- When you subscribe to the Marietta Systems' c_wndw software you are entitled to the following: a) A copy on 360 Kbyte 5.25" diskette(s) of the latest version of the software for your selected C compiler with: * Full set of memory models * The source code for six of the functions: helpmenu, helpscrn, mrt_brk, prn_scrn, top_spot, warble. * Any enhanced facilities of the c_wndw software The subscription fee includes the cost of distribution and handling, normally chargeable at $9.00. b) The official manual for Marietta Systems' c_wndw software that features: * Full description of the c_wndw functions * Major section on customization * Guidance on making full use of the software * Documentation on using the reserved functions * Full error code analysis section * Documentation of the key and function key usage This manual has a value of $18.00, but is only available with your subscription, or as part of a corporate or educational license agreement. c) Your first year's membership of the Marietta Systems' c_wndw Error Reporting and Notification Service, currently worth $14.00, which provides: * Periodic notification of known errors and idiosyncrasies * Access to the latest versions of the software * Acknowledgment of any bugs you properly document to us * Waiver of handling and distribution fees on the next software release to the first person to properly document to us a new bug in our c_wndw software d) A non-exclusive, non-transferable license to use the full version of the c-wndw software on a single computer system. This license has a value of $30.00, and is only available with this subscription, or as part of a corporate or educational license agreement. The $35.00 subscription fee is a $70.00 value. Subscribe now and get the official manual and latest software described above. c_wndw Subscription form - 1.03 =============================== Mail to: Marietta Systems, Inc c_wndw Subscription P.O. Box 71506 Marietta, GA 30007 USA Your name ______________________ Company ______________________ Street ______________________ Suite/apt ______________________ City ______________________ State/prov _____ Zip/postcode ___________ Country ___________ Phone number (_____)__________ Where did you get the shareware software?______________________ Your computer: System model ____________________ (ex; IBM PC/XT) Hard disc MByte _________ (ex; 20MB) Memory in Kbyte _________ (ex; 512 KB) Color or Mono? _________ Monitor adapter _________ (ex; CGA) Printer _________ (ex; Okidata 192+) Operating system ____________ (ex; MS/DOS v3.10) (please specify version number) Which C compilers do you support? Borland's Turbo C - (Y / N) version _______ Lattice C - (Y / N) version _______ Microsoft Quick C - (Y / N) version _______ Note: one set of software for a C compiler is provided with the subscription fee, additional sets are available for an extra dist & hdlg fee of $9.00 each. Other C compilers (please specify) __________________________ Please enclose a check or money order in US Dollars for the following amount: 1 Subscription fee US $ 35.00 __ Additional sets of s/w for more than one C compiler @ $9.00 for dist & hdlg $______ USA and Canada shipping charge @ $2.00 $______ Overseas shipping charge @ $9.00 $______ Georgia residents add $1.85 sales tax $______ TOTAL enclosed $______ Note: We may not be able to ship to some overseas countries. 2. INSTALLATION ============ 2.1 System Configuration -------------------- The standard shareware diskette contains a set of software for Quick C, and Turbo C users. This software is available from ourselves or through a shareware distribution organization. The software provided is as follows: complink.qui A compile, link and run batch file for Quick C complink.tur A compile, link and run batch file for Turbo C c_wndw.h Header file for c_wndw software c_wndw.qui Quick C library for Small memory model c_wndw.tur Turbo C library for Small memory model quickc.bat Installation batch file for Quick C turboc.bat Installation batch file for Turbo C summary.doc This document mtest.qui Quick C "#include" file for sample programs mtest.tur Turbo C "#include" file for sample programs readme Instructions on printing this manual *.c Sample C programs showing use of c_wndw software *.prj Turbo C project make files for sample programs You will need a PC, PC-XT, or PC-AT compatible system running MS/DOS or PC/DOS of version 2.1 or later, and a monochrome or CGA-compatible color adapter. The software will run with an EGA adapter. You will also need a copy of Borland's Turbo C or Microsoft's Quick C. For installation, you will need access to a suitable PC with a diskette drive plus either a second diskette drive or a hard disc. The installation and compilation batch files assume a hard disc, and will need modifying if you are using this in a diskette-only environment. The software requires, at least, an 80 column width display. It will make full use of color if available. For installation, your PC must be configured for 80 column, 25 line mode, using color if available. 2.2 Installation Procedure ---------------------- 1) Place the distribution diskette in the first diskette drive (drive a:), and type: for Quick C A:QUICKC for Turbo C A:TURBOC 2) The jobstream will now check for file "stdio.h" in the chosen directory on the default disc drive. If this file cannot be found, the jobstream will terminate. 3) The jobstream will now copy the files. 2.3 Linking and headers ------------------- Place the header file in those programs that will be using our software, ensure that the file follows the standard headers: #include <c_wndw.h> Modify your link command to include our library, "c_wndw". For example: Quick C, the command line compilation and linking needs to access the c_wndw library. See our run batch file COMPLINK for a working example. Note that this batch file assumes that the standard Quick C libraries SLIBC.LIB and LIBH.LIB are available to it. You may need to copy these off your Microsoft issue diskettes. Turbo C has two compilation and linking environments. The integrated development environment needs to have .PRJ files setup for each program with the line \turboc\lib\c_wndw.lib The TCC command line compiler needs to have \turboc\lib\c_wndw.lib added to the end of the command line. See our run batch file COMPLINK for a working example. A batch file, COMPLINK.BAT, is supplied that will compile, link and run the sample programs. Enter the command COMPLINK program where 'program' is the name of the program without the '.C' suffix. Note that we were only able to fit the code for the Small memory model for each type of C compiler on the shareware diskette. This means that Quick C users cannot use the 'programming environment' which requires the Medium model. The other memory models are supplied when you send in your subscription fee. 3. QUICK REFERENCE =============== These functions are designed for the novice and intermediate C programmer and feature extensive parameter checking and error trapping. Error messages are output the the Error Area on the screen and held there typically for 2 seconds before the program continues running. In addition the functions will, where possible, deduce sensible alternate values for erroneous parameters. This defensive programming technique has a minor performance cost, and experienced programmers will want to take advantage of source code availability under the Development license agreement. The functions are provided in seven classifications:- Console input/output functions accept, check_f, display, disp_err, disp_msg, disp_qry, grabchar, helpscrn, idleloop, isendch, read_kb, warble Date functions datecomp, datelong, datemath, dateread, date_in, date_out Disc file access functions dbf_fld, fileback, fileclos, filedbf, fileinit, fileopen, fileread, fileseek, filewrit, file_err, hashmake, hashread, scrnsave Field manipulation functions concat, fld_len, justify, primenbr, validate, v_bool Initialization and exit functions clr_scrn, goodbye, mrtbrk Menu control functions helpmenu, menu, top_menu Window control functions box_scrn, clr_wndw, mk_wndw, prn_scrn, rm_wndw, scrn_map, scroll, set_clr, set_crsr, top_spot 3.1) Console Input/Output: -------------------------- int accept(byte* field, enum _JUST just, enum ATTRIB atb, int len, int dec) Accepts entry of a field at the current cursor position with justification 'just', length 'len' with 'dec' decimal places, and color pair attribute 'atb.' The function returns negative for error, zero if the ENTER key is used, and 1 if a valid function key is used. The function key code is stored in INCHAR. z = accept(money, decimal, alt_low, 7, 2); z = accept(text, left, reverse, 25, 0); void check_f(void) A reserved function used by the 'grabchar' function. void display(byte* field, int rx, int ry, enum ATTRIB atb) Displays the field at cursor position (rx, ry) within the current window with the color pair attribute 'atb'. The string can contain any of the IBM graphics characters, in addition, to the ASCII character set. display("Enter invoice number", 4, 1, alt_low); display(heading, 10, 2, high); void disp_err(char* text, int errcode) Displays the text and the error code 'errcode' in the Error Area on the right half of the bottom line of the screen. A short tone will also be sounded. The codes 200 through 999 are reserved by the "c_wndw" software. disp_err("You must enter digits 0 to 9", 1001); void disp_msg(char* test,int errcode) Displays the text and the error code 'errcode' in the Message Area on the left half of the screen's bottom line. disp_msg("Review, then press any key to continue", 1); byte disp_qry(char* qrytext) Displays the query test the the Message area, and elicits a Y/N response. Returns zero for 'N', and 1 for 'Y'. if (disp_qry("Do you want to continue")) continue; byte grabchar(void) Returns converted entry character and also sets this value into INCHAR. All key stroke entries, including function keys, are converted into a single byte value. int helpscrn(byte* field) A reserved function that makes the help screen for 'accept'. void idleloop(int ticks) Used for a delay of the clock ticks provided. 18 ticks to the second, 1092 to the minute. int isendch(byte* field, byte c, enum ATTRIB atb) A reserved function used by the 'accept' function. void read_kb(void) Accepts and discards a keyboard entry. void warble(int tone) Sets the speaker to the tone provided. A tone of zero shuts off the speaker. 3.2) Date functions: -------------------- Note: Dates are stored as unterminated 3 char arrays in compressed format. Years in the range 1853 to 2107 can be stored in this format. int datecomp(char* d1, char* d2) Compares two compressed dates, returning zero if equal, positive if 'd1' is higher, and negative otherwise. long datelong(char* d1) Converts the compressed date 'd1' to a count of the number of days since 1/1/80. For example: Jan 2, 1980 will yield (1L), and Dec 31, 1979 will yield (-1L). void datemath(char* d1, int days) Adds the specified number of days to the compressed date 'd1'. The 'days' variable can be negative for subtraction. datemath(d1, 60); /* increments the date in d1 by 60 days */ void dateread(char* d1) Accesses the system clock to gets today's date in compressed format. void date_in(char* d1, char* text) Converts to an 8 char formatted date (ex: 10/11/82) to compressed 3 char format. void date_out(char* text, char* d1) Converts a compressed date to a 8 character formatted date. 3.3) Disc file input/output: ---------------------------- Note: These functions trap disc errors, and display a message to the Error Area of the screen. If retry is sensible (ex: illegal disc change), the functions will give the operator the option of retrying or abandoning the operation. It is not necessary for the programmer to be concerned with 'errno' or the various DOS error codes. int dbf_fld(int fh) This returns the number of fields in the data dictionary of a 'dbase3'-type or 'hashed'-type file. int fileback(char* fname) This erases any prior file with the ".bak" extension, and then renames the named file to have the ".bak" extension. The backed- up file is set read-only. The function returns negative on error, zero if the file with name 'fname' cannot be found, or positive for success. int fileclos(int fh) Closes the file with file handle 'fh'. Returns zero for success, negative for error, or zero if the file is already closed. int filedbf(int fh) Used by the 'fileopen' function to setup the dBase III Plus data dictionary for a valid 'dbase3'-type file. int fileinit(int fh, int start, int rec_len, long max_rec) Initializes values in the struct FN[fh] for the record length 'rec_len', record count 'max_rec', and size of any header area at the front of the file in 'start'. The function returns zero for success, and negative for an error. It is not necessary to use this for 'hashed'-type or 'dbase3'-type files as this information is loaded automatically by 'fileopen'. int fileopen(char* fname, enum F_TYPE type, enum F_MODE mode) Opens the file given by 'fname' with file-type 'type' and under file-mode 'mode'. The function returns negative for an error, zero if the file cannot be found, or the positive file handle value if successful. fh1 = fileopen("testfile.doc", ascii, append); fh2 = fileopen("c:\data\datafile.dbf", dbase3, update); int fileread(int fh, enum F_READ mode, long* rec_nbr) Reads a record from a file with read-mode 'mode'. The record number 'rec_nbr' is used for 'relative' reads, and, for all reads, contains the value of the record number following the record read. The function returns zero for success or negative for error. The record is read into 'FN[fh].record'. z = fileread(fh1, nextrec, &rec_nbr1); z = fileread(fh2, relative, &rec_nbr2); int fileseek(int fh, long loc) Performs a seek on the file to a specified byte location. This function will be rarely used as the 'fileread' function performs positioning as required. int filewrit(int fh, long* rec_nbr) Write 'FN[fh].record' to the file. For 'append' and 'recreate' access-mode files, the record will always be written to the end of file, but for 'update' mode will be written to the specified record number. The record number will be set to the next record following the one written. The function returns negative on error, zero for success. int file_err(int fh, int count) A reserved function used by file access functions. int hashmake(char* fname, int fields, int rec_len, long max_rec, int key_off, int key_len) Creates an empty hashed file of name 'fname', record length 'rec_len', and 'max_rec' pre-allocated records. The location of the hash key within the record is starts at position 'key_off' and length 'key_len'. The returns are as for the 'fileopen' function. The file is left open in 'update' mode. fh3 = hashmake("filetest.hsh", 10, 400, 1700L, 5, 8); long hashread(int fh, byte* key, int access) Performs hashed read to an opened 'hashed'-type file using the array 'key'. The 'access' code should be zero to indicate that a matching key is required, and 1 if an empty record is required (for an insert). The function will return negative for error or a positive number of the record number read. z = hashread(fh, (byte*)value, 0); void scrnsave(int posn) A reserved function used by 'accept', 'read_kb' and 'display' functions. 3.4) Field manipulation: ------------------------ byte* concat(byte* field, int spaces) Strips trailing spaces off the string 'field', optionally adding 1 or 2 depending on value of 'spaces'. The function returns a pointer to the new end of the string. int fld_len(enum _JUST just, int len, int dec) Returns required size of a string to hold a field with justification 'just' and size 'len' with decimal places 'dec'. For numeric fields, the 'len' parameter refers to the digits before the decimal point. len = fld_len(decimal, 7, 2); void justify(enum _JUST just, byte* s1, byte* s2, int len, int dec) Copies and justifies string 's2' into string 's1', using the length parameters 'len' and 'dec'. This function is used for automatically expanding and truncating strings, and for formatting and extracting numeric fields. justify(center, s1, s2, 25, 0); justify(decimal, n1, s2, 7, 2); int v_bool(char c) Returns 1 if 'N', 2 if 'Y', otherwise zero. 3.5) Initialization and exit: ----------------------------- void clr_scrn(char* title) This function must be called at the start of the program to initialize the window and file buffers used by the "c_wndw" software. It also clears the screen and sets up the base window #0. The title is displayed centered on the top line. The opening can be shortened by setting a configuration variable. clr_scrn("Main screen title"); void goodbye(short errcode) This function must be used to end the program. It closes the files and resets the configuration changes made by the 'clr_scrn' function. The function does not return but calls the 'exit' function with the provided 'errcode' to end the program. An 'errcode' of zero is a normal exit, and non-zero is an error exit. Codes of 200 through 254 are reserved by the "c_wndw" software. int mrtbrk(void) A reserved function containing the CTRL+C break handling code. 3.6) Menu control: ------------------ int menu(char* menutext, int size, int start, int up) Displays the menu from the string 'menutext' within the current window starting from the current cursor position. Each menu item must be terminated with a '&' character. The function will display the items with a maximum size of 'size' and with 'up' items per line. A full screen size window with (size = 8) and (up = 9) can accommodate up to 207 menu items. The 'start' parameter indicates which item is to be initially highlighted. The function returns negative for error, zero if the F10 (EXIT) key is used, or a positive number corresponding to the item selected. item = menu("Compact&Huge&Large&Small&", 8, 1, 1); int top_menu(char* menutext, int size, int start) This function displays the menu across the top line of the screen. The items have a maximum size of 27 bytes and the full menu must fit on one line. The returns are as for the 'menu' function. item = top_menu("Lattice C&Quick C&Turbo C&", 12, 3); void helpmenu(int item) A reserved function that provides the help screen for both menu functions. 3.7) Windowing functions: ------------------------- Note: The number of the current window is held in variable W_NUM, and its size and location in the struct WINDOW[W_NUM]. Each window is provided automatically with a set of 6 color pairs which are different from the prior and following windows, and the top and bottom screen lines. void box_scrn(void) Reserved function used by the 'mk_wndw' function. void clr_wndw(void) Clears the current window. int mk_wndw(int ax1, int ay1, int ax2, int ay2, byte* title) Creates a window from the coordinates of its top left hand corner (ax1, ay1), and bottom right hand corner (ax2, ay2). The window is boxed in with double lines for delineation on monochrome screens and for additional visual impact on color screens. The 'title' is centered over the top of the window. The function returns negative on error, or a positive number corresponding to the window just created. w = mk_wndw(5, 5, 15, 75, "Test window"); void prn_scrn(void) A reserved function activated by the "Alt+P" key combination that prints a translated copy of screen onto the main printer. This works with any printer as the IBM graphics characters used by the 'mk_wndw' function are translated to ASCII equivalents. int rm_wndw(void) Removes the current window. The function returns negative on error, or a positive number corresponding to the window just removed. (Window #0 cannot be removed.) void scrn_map(byte* field, int ax, int ay) A reserved function that places the 'field' onto the screen starting at the (ax, ay) location. void scroll(int incr, int head) Scrolls the window up or down according to the 'incr' parameter, leaving a heading area of 'head' lines unscrolled. scroll(2, 3); void set_clr(int wndw, enum ATTRIB atb) A reserved function used to change the color code. void set_crsr(int rx, int ry) Moves the cursor within the current window to the location given by (rx, ry). set_crsr(3, 10); void top_spot(int val) Refreshes the status values on the top line of the screen. These status values are the screen title, available memory, character insert status, date, and available capacity on the default disc drive. A 'val' of zero refreshes the whole line, (1) refreshes the available memory, and (3) refreshes available disc. 3.8) Special definitions: ------------------------- enum ATTRIB {low, high, reverse, blink, blank, alt_low, alt_high, alt_reverse}; Defines the screen attribute code that selects which of the 6 color pairs are to be used, plus supports 'blink' and 'blank' fields. This is used with the 'accept', 'display', 'set_clr' functions. enum COLOR_OF {black, blue, green, cyan, red, magenta, yellow, white}; Defines the 8 base colors used by the software, which extend to 16 with the high/low intensity options. enum fld_type {alphanum, graphic, flag, boolean, calendar, numeric, value, real, chrono}: Defined for future use. enum F_READ {firstrec, previous, nextrec, lastrec, random, relative}; Defines file read mode for the 'fileread' function. Note that not all file types support all read modes. enum F_MODE {append, readonly, recreate, update}; Defines the file access mode for the 'fileopen' function. All access modes are available with all file types except 'append' with 'hashed', and 'update' with 'ascii'. enum F_TYPE {ascii, binary, dbase3, hashed, marietta}; Defines the file type for the 'fileopen' function. 'ascii' type files have variable length records terminated with "\r\n", whereas 'binary', 'dbase3', and 'hashed' files have fixed length records which may contain binary information. enum _JUST {left, right, as_typed, center, code, decimal, c_number, date, time}; Defines field format (justification) codes used by the 'accept', 'fld_len', and 'justify' functions. Note that 'time' is not currently supported. struct CURSR {byte X,Y;} _CURSOR; Contains current cursor location within current window. typedef unsigned char byte; 4. REVIEW OF SAMPLE PROGRAMS ========================= The sample programs provided with this software release cover two areas, that of simple programs to demonstrate a facility of the software, and that of full programs demonstrating the use of the functions in general. We recommend that you compile and run the sample programs in the following sequence to get an understanding of the "c_wndw" functions facilities, before you address the complexity of the large sample programs. The Official Manual available from Marietta Systems, Inc. with your registration fee gives full details on the functions, error messages and the customization variables. Some techniques you may not understand will be explained in that manual. To compile, link and run a sample program, ensure that you are in the correct directory (\TURBOC for Turbo C and \QC for Quick C), and type in COMPLINK program where 'program' is the name of the test program without the ".C" file extension. (ex: COMPLINK JUSTIFY1 ) 4.1) window ----------- This program overlays five windows on the screen, showing the ease and speed that windows can be created and removed. The program also shows the maximum boundaries of windows, and what happens when you are on the boundary. 4.2 Color --------- This program demonstrates the full range of color variations available with the standard setup of the c_wndw toolkit. If you amend the default color selections, run this program to check out your changes. If your printer is available, press the Alt+P keys to print the screen. 4.3) display1 ------------- This program shows the visual effect of the different values of the 'enum ATTRIB' and the action of the 'display' function within a window. 4.4) scroll1 ------------ This program demonstrates the operation of the 'scroll' function. 4.5) cursor1 ------------ This program shows how the cursor is moved within a window, and how the 'set_crsr' function corrects cursor coordinates outside of the window. 4.6) justify1 ------------- This program demonstrates how the 'justify' function is applied to handling the source string for a set of different justify commands, and field sizes. Note that the numeric-type justifications read the source field from right to left, performing decimal alignment as necessary. 4.7) warble1 ------------ This program uses the 'warble' and 'idleloop' functions to produce a descending series of tones. 4.8) accept1, accept2, accept3 ------------------------------ These programs accept input of a column of fields to demonstrate the use of the 'accept' function. The 'accept1' program has a column of numbers, the 'accept2' program has a column of dates, and the 'accept3' program has a column of centered text strings of increasing size. Note the validation of dates, and of the size of the number. Try entry with INS:ON and INS:OFF to see the difference. Use the F2-UNDO key to undo changes to a field. Press the F1-HELP key for the help window. 4.9) disp_xxx ------------- This program demonstrates the use of the 'disp_err', disp_msg', disp_qry' and 'read_kb' functions. 4.10) menu_xxx -------------- This program demonstrates the use of the 'top_menu' and 'menu' functions. Notice that if the menu items are in ascending sequence, with initial characters in uppercase, how you have the option of keying in the name or selecting the item using the cursor control keys. Also press the F1-HELP key to see the standard help screen. 4.11) filetest -------------- This program performs sequential reads and writes to 'ascii'-type and 'binary'-type files. It first creates and then writes to an 'ascii'- type file. The file is closed, re-opened, and read sequentially. The program then creates a 'binary'-type file, and copies to it from the 'ascii'-type file. Lastly, the 'binary'-type file is read backwards. 4.12) writtest -------------- This program reads the 'ascii'-type file created by the previous program and copies to a 'binary'-type file. You can then retrieve any record randomly by its record number, and optionally amend the contents of the record. This is the first example of the function key control facilities, to activate the F8-AMEND key. 4.13) hashtest -------------- This program creates a 'hashed'-type file, and then switches into data entry mode to allow you to insert, delete, view, or amend records in the file. Note the activation of the F5-INSERT, F6-DELETE, and F8- AMEND keys for this purpose. At the end of the program, it reads through the file and gives you an analysis of the records EMPTY, IN_USE, and DELETED. 4.14) bracket ------------- This is a cute little programming aid that reads through a program source file and shows each line with a '{' or '}' character. The program also displays the line number and the '{' increment number. Why not try this on the "hashtext.c" source code. You could amend the program to ignore '{' and '}' within comments. 4.15) textedit -------------- This is a line-oriented text editor. It demonstrates a sophisticated use of the control and function keys, and a wide variety of the "c_wndw" functions. This includes the 'fileback' function to backup the current text file before you write out the old file. It has a few bugs so do not use it on live files unless you correct them. 4.16) dbfdict ------------- This program creates the data dictionary for a dBase III Plus compatible ".dbf" file. Again this incorporates some sophisticated use of the facilities of the "c_wndw" software to achieve this aim. You could add scrolling facilities (using 'textedit' as an example) to allow it to handle the full 128 fields supported by dBase III Plus. In addition, you could save an existing data dictionary for amendment instead of starting anew each time. 4.17) dbfedit ------------- This program uses the data dictionary of a dBase III Plus compatible file to insert, delete, view, or amend records at the field level. Use the file you created with 'dbfdict. Notice the use of the F3- SEARCH key to initiate a non-context search. You could improve this program by allowing long records to spill onto multiple screens (using 'textedit' as an example) and support the full 128 fields allowed by dBase III Plus, or even index fields by setting up 'hashed'-types files with a key and record number. 5. HEADER FILES ============ Each of the C compilers has some differences in header files and the minimum set of header files for each compiler is provided below. The 'install' jobstream will have placed a special file "mtest.h" in the sub- directory "/MARIETTA" with these header files defined. 5.1 Microsoft Quick C header files ------------------------------ #include <bios.h> #include <conio.h> #include <ctype.h> #include <dos.h> #include <fcntl.h> #include <io.h> #include <malloc.h> #include <stddef.h> #include <stdio.h> #include <stdlib.h> #include <string.h> #include <c_wndw.h> 5.2 Turbo C header files -------------------- #include <alloc.h> #include <conio.h> #include <ctype.h> #include <dir.h> #include <dos.h> #include <fcntl.h> #include <mem.h> #include <stddef.h> #include <stdio.h> #include <stdlib.h> #include <string.h> #include <c_wndw.h> 6. CUSTOMIZATION ============= The configuration constants in the header file <c_wndw.h> can be amended to customize this software. All are implemented as variables, rather than '#define' constants, to allow their values to be set by software. Some of these "constants" can be dynamically changed by your program, while others should never be changed after the 'clr_scrn' function is first called to initialize the system. All the constants come with sensible default values, and it is not necessary to set them to test out the system. 6.1 "Hard" Constants ---------------- These constants must not be changed after the 'clr_scrn' function is called to initialize the system. DISCBLCK The maximum record size of any file to be accessed. MAX_WIND The maximum heap space to be used for window functions. MEM_WARN The memory-low warning level. TOP_LINE The number of lines dedicated for status and the 'top_menu' function at the top of the screen. SCRN_LEN The number of lines on the screen. SCRN_WID The number of columns on the screen. _COLOR The maximum number of color pairs. _WINDW The maximum allowed number of windows. 6.2 Internationalization -------------------- These constants must not be changed after the 'clr_scrn' function is called to initialize the system. They are provided to support common inter- national variations. D_FORMAT Provides the date format to be used: 'U' = mm/dd/yy; 'E' = dd/mm/yy; 'I' = yy/mm/dd D_PUNCT Identifies the punctuation character for dates. PERIOD Identifies the decimal point character. COMMA Identifies the thousands separator character. BOOL_YES Identifies the uppercase boolean yes/true code. BOOL_NO Identifies the uppercase boolean no/false code. 6.3 "Soft" Constants ---------------- ACC_DISP The attribute used by 'accept' after entry. D_20XX Identifies the split between the 20th and 21st centuries for two digit year fields. ERR_BEEP Length of the error beep used by 'disp_err' function. FLD_FULL 1 = auto enter on full field; 0 = requires ENTER. KEYMATCH See section 6.5. 6.4 Setting the colors ------------------ The colors should be amended in the header file, or revised prior to the 'clr_scrn' function being called to initialize the system. There are three color constants, COLOR[], TOP_CLR, and ER_COLOR. Each variable uses the struct CLR_TYPE. The color constant array COLOR[] defines the color sets available to the windows. The ALT_CLR code is the number of the alternate color set to be used for the 'alt_low', 'alt_high', and 'alt_reverse' attributes. The TOP_CLR constant determines the color pair to be used for the status line and 'top_menu' function. The ER_COLOR constant determines the color pair to be used for the bottom message and error line. 6.5 Controlling the function keys ----------------------------- The 'isendch' function uses a controlling array (KEYMATCH) to determine which possible function keys are supported by your program. Setting applicable values into this array will enable or disable function keys. All function keys are translated to ensure that all ASCII and non-ASCII key combinations are represented as a single byte code Generally, Wordstar conventions are followed by, for example, overlapping 'Ctrl+E' and left cursor on the same code. The codes are translated by the 'check_f' function, whose source code is available with a full software release. Value Function key Ctrl key W/str Preset meaning to 'accept'? ----- ------------ -------- ----- --------------------------- 3 PgDn * No 4 Right cursor Ctrl+D Y Yes 5 Up cursor Ctrl+E Y No 7 Del Ctrl+G Y Yes 8 Backspace Ctrl+H Y Yes 9 TAB Ctrl+I Y Yes 10 Ctrl+Enter Ctrl+J * Yes (if enabled) 11 Shift+TAB Ctrl+K N Yes 18 PgUp Ctrl+R Y No 19 Left cursor Ctrl+S Y Yes 20 Ctrl+B/space Ctrl+T Y Yes - blank out field 22 Ins Ctrl+V Y Yes 23 Home Ctrl+W Y No 24 Down cursor Ctrl+X Y No 26 End Ctrl+Z Y No 27 Esc Ctrl+[ Y Yes 7. ERROR REPORTING =============== Your subscription fee provides you with a one year membership of our c_wndw Error Reporting and Notification Service. The service provides you with: a) Notification, via a newsletter, of known errors for a year with work- arounds, if known. b) Access to the latest version of the software with bug fixes and enhancements. c) Acknowledgment of bugs and idiosyncrasies you report to us. d) Waiver of handling and distribution fees on the next software release to the first person to properly document a new bug for us in our c_wndw software. (We would like to think that there are no bugs) The subscription form is on Page 4. New users of the software who have not yet paid their subscription fee may obtain from us, free of charge, a list of any known bugs in the software provided through the shareware distributors, and suggested work-arounds. We will also be pleased to receive your comments and and views on the software, this manual, and how to improve and enhance this product. Write to us at: Marietta Systems, Inc. c_wndw Error Service P.O. Box 71506 Marietta, GA 30007 USA 8. FUTURE ENHANCEMENTS =================== This is the first release of the c_wndw software which provides you with windowing and file access software. We have developed plans for future enhancements of this software, and would like to share them with you. The priority for enhancements is in the file access area. We intend to provide a b-tree based multiple index ISAM handler (the currently unused 'marietta' file type), and generally improve performance for sequential reading and writing. We also intend to expand support of the dBase III Plus file structure, as a well supported and defined database structure. Record locking is currently partially handled, as the 'fileread' and 'filewrit' functions have a retry procedure for locked records, but do not lock records themselves. The design will be that 'fileread's on files opened 'update' will automatically set record locks, to be released on the next 'fileread', 'fileseek' or 'filewrit' to that file. We would also provide a new function to release unwanted locks without causing a read or write. We also intend to vigorously attack any software bugs or environmental dependencies in our "c_wndw" software, so please isolate and document them to us if you find any. We believe that there are no significant bugs, but want to know if we are wrong. On the screen handling side, we intend to be compatible with major C graphics toolkits, and to provide a Windows/Presentation Manager version of this package. Well, grand plans, but it is essential that those subscription fees keep coming in to help us finance these enhancements. The subscription fee is really worthwhile. The Official Manual is far more usable than this one, and has lots of other useful information and indexes. So subscribe, and help us take this product forwards. Look forward to hearing from you!!